---
title: 使用自定义字体
sidebar:
  label: 字体
description: >-
  想要为 Astro 生成的网站添加一些自定义的字体？
  使用 Google Fonts 或者使用本地文件以添加自定义字体。
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import { Steps } from '@astrojs/starlight/components'

本指南将向你展示如何将网页字体添加到你的项目中，并且在组件中使用这些字体。

:::tip[实验性字体 API]
了解有关 Astro 的 [实验性字体 API](/zh-cn/reference/experimental-flags/fonts/)，该功能允许你通过统一、完全可定制且类型安全的 API，来使用这些来源的字体：本地文件系统，字体提供商。
:::

## 使用本地字体文件

这个例子将演示使用字体文件添加自定义字体 `DistantGalaxy.woff`。

<Steps>
1. 添加你的字体文件到 `public/fonts/` 目录。
2. 将以下`@font-face` 语句添加到你的CSS中。它可以位于你引入的全局 `.css` 文件，或在`<style is:global>` 块中， 也可以是你想要使用字体的特定布局或组件中的 `<style>` 块中。

    ```css
    /* 注册你的自定义字体并告诉浏览器它在哪里 */
    @font-face {
      font-family: 'DistantGalaxy';
      src: url('/fonts/DistantGalaxy.woff') format('woff');
      font-weight: normal;
      font-style: normal;
      font-display: swap;
    }
    ```

3. 使用 `font-family` 值为组件或布局中的元素设置字体样式。在此示例中，自定义字体将应用于 `<h1>` 标题，而不会用于段落 `<p>`。

    ```astro title="src/pages/example.astro" {9-11}
    ---
    ---

    <h1>In a galaxy far, far away...</h1>

    <p>Custom fonts make my headings much cooler!</p>

    <style>
    h1 {
      font-family: 'DistantGalaxy', sans-serif;
    }
    </style>
    ```
</Steps>

## 使用字体资源包

[Fontsource](https://fontsource.org/)（字体资源包）项目简化了使用 Google Fonts 和其他开源字体的使用。它提供了 npm 模块，你可以为要使用的字体安装。

<Steps>
1. 从 [Fontsource 的目录](https://fontsource.org)中找到你想用的字体。此例子将选择 [Twinkle Star](https://fontsource.org/fonts/twinkle-star)字体。
2. 安装你选择的字体的包。

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm install @fontsource/twinkle-star
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm add @fontsource/twinkle-star
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn add @fontsource/twinkle-star
      ```
      </Fragment>
    </PackageManagerTabs>

    :::tip
    你可以在 Fontsource 网站上每个字体页面的“快速安装”部分找到正确的包名称。包名总是以 `@fontsource/` 或 `@fontsource-variable/` 字体名称开头。
    :::

3. 在要使用字体的布局或组件中导入字体包。通常，需要在通用布局组件中执行此操作，以确保该字体在你的网站上可用。

    导入（import）将自动添加 `@font-face` 以设置字体所需的必要属性。

    ```astro title="src/layouts/BaseLayout.astro"
    ---
    import '@fontsource/twinkle-star';
    ---
    ```

4. 使用字体名称作为 `font-family` 值，正如 Fontsource 网站中的例子所示。这适用于任何可以在 Astro 项目中编写 CSS 的地方。

    ```css
    h1 {
      font-family: "Twinkle Star", cursive;
    }
    ```
</Steps>

为了优化网站的渲染时间，你可能需要预加载初始页面显示所必需的字体。
有关更多信息和用法，请参阅 [Fontsource 的预加载字体指南](https://fontsource.org/docs/getting-started/preload)。

## 在 Tailwind 中注册字体

如果你使用的是 [Tailwind](/zh-cn/guides/styling/#tailwind)，则可以使用此页面的前述方法之一来安装字体，并进行一些修改。你也可以使用[`@font-face` 语句注册本地字体](#使用本地字体文件)，或使用 [Fontsource 的 `import` 策略](#使用字体资源包)去安装你的字体。

要在 Tailwind 中注册你的字体：

<Steps>
1. 请遵循上述任一指南，但跳过添加 `font-family` 到 CSS 的最后一步。
2. 将字体名称添加到 `src/styles/global.css`。

    此示例将添加 `Inter` 到 sans-serif 字体堆栈。

    ```css title="src/styles/global.css" ins={3-5}
    @import 'tailwindcss';

    @theme {
      --font-sans: 'Inter', 'sans-serif'; 
    }
    ```

    现在，项目中的所有 sans-serif 文本（Tailwind 的默认设置）都将使用你选择的字体，并且该类 `font-sans` 也将应用 Inter 字体。
</Steps>

有关的更多信息，请参阅[Tailwind 中关于添加自定义字体系列的文档](https://tailwindcss.com/docs/font-family#using-custom-values)。

## 更多资源
- [在 MDN 的网站字体指南](https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts) 中了解网站字体的工作原理。
- [使用 Font Squirrel 的 Webfont Generator](https://www.fontsquirrel.com/tools/webfont-generator)为你的字体生成 CSS。
